Jenkins 配置 Node.js 构建环境
安装 NodeJS 插件
插件安装
- 进入 Manage Jenkins → Plugins → Available plugins
- 搜索 NodeJS
- 安装 NodeJS Plugin（当前版本 1.6.1+）
- 安装完成后 Jenkins 会自动重启
该插件类似于 NVM 的版本管理工具，支持在 Jenkins 中配置多个 Node.js 版本，按需选用。
插件核心能力
| 能力 | 说明 |
|---|---|
| 多版本管理 | 可安装多个 Node.js 版本，任务级别选择 |
| 国内镜像加速 | 支持配置淘宝源下载 Node.js |
| 全局包管理 | 自动安装 cnpm、pnpm、yarn 等全局工具 |
| 自定义 npm registry | 支持 .npmrc 配置文件管理 |
全局工具配置
配置 Node.js 安装
进入 Manage Jenkins → Global Tool Configuration，滚动到底部找到 NodeJS 部分。
基本配置
点击 Add NodeJS，按以下步骤配置：
| 配置项 | 值 | 说明 |
|---|---|---|
| Name | node18 | 自定义别名，后续任务中引用 |
| Installation | Install from nodejs.org mirror | 使用镜像源下载 |
| Mirror | https://npmmirror.com/mirrors/node/ | 淘宝 Node.js 下载镜像 |
| Version | 18.15.0（或选择需要的版本） | 根据项目需求选择 |
| Credentials | 无需配置 | 公共下载不需要凭证 |
注意：镜像地址是 Node.js 下载源（mirrors），不是 npm registry（register）。二者地址不同：
- Node.js 下载源：
https://npmmirror.com/mirrors/node/- npm 包加速源：
https://registry.npmmirror.com/
全局包安装
勾选 Global npm packages to install，添加常用的全局工具包：
cnpm pnpm yarn
text
建议同时配置 registry 参数，确保全局包从淘宝源安装。
工具目录
| 场景 | 推荐路径 |
|---|---|
| 测试环境 | /tmp 目录 |
| 生产环境 | /home/node/18 或 /opt/node/18 |
标签配置
标签（Label）用于指定 Node.js 环境安装在哪台机器上：
- 默认：安装在 Jenkins Master 主机上
- 自定义标签：安装到指定标签的工作节点上
配置示例
# Node.js 16 配置
Name: node16
Mirror: https://npmmirror.com/mirrors/node/
Version: 16.x
Global Packages: cnpm pnpm yarn
Tool Directory: node/16
# Node.js 18 配置
Name: node18
Mirror: https://npmmirror.com/mirrors/node/
Version: 18.15.0
Global Packages: cnpm pnpm yarn
Tool Directory: node/18
yaml
npm Registry 配置
方式一：全局工具配置中设置
在 NodeJS 全局工具配置的 Global npm packages to install 中，给每个包添加 --registry=https://registry.npmmirror.com/ 参数。
方式二：创建 .npmrc 配置文件
- 进入 Manage Jenkins → Managed files
- 点击 Add a new Config
- 选择 Npm config file
- 点击 Next
- 命名（如
npmrc-config-custom） - 在配置内容中设置 registry：
registry=https://registry.npmmirror.com/
ini
- 点击 Submit 保存
Cypress 下载镜像配置
Cypress 依赖包较大，需要单独配置全局下载镜像。
配置环境变量
- 进入 Manage Jenkins → System Configuration
- 找到 全局属性 → 环境变量
- 添加键值对：
| 键 | 值 |
|---|---|
CYPRESS_DOWNLOAD_MIRROR | https://npmmirror.com/mirrors/cypress/ |
- 保存
任务中使用 Node.js 环境
启用 Node.js 构建环境
- 进入任务的 Configure 页面
- 找到 Build Environment 区域
- 勾选 Provide Node & npm bin/ folder to PATH
- 选择对应的 Node.js 版本（如 node16 或 node18）
- npmrc file 选择 Custom config，选择之前创建的
.npmrc配置
配置构建步骤
添加 Execute shell 构建步骤：
# 验证 registry 配置
npm config get registry
# 打印 Cypress 镜像地址（验证环境变量）
echo $CYPRESS_DOWNLOAD_MIRROR
# 安装依赖
pnpm install
# 构建项目
pnpm build
# 查看构建产物
ls -la dist/
bash
构建步骤之间的拖拽排序
Jenkins 支持通过拖拽调整构建步骤的执行顺序，灵活性很高：
步骤1: npm config get registry (验证)
步骤2: pnpm install (安装依赖)
步骤3: pnpm build (构建)
步骤4: ls -la dist/ (检查产物)
text
构建验证与常见问题
ARM 架构兼容性问题
如果在 ARM 架构的虚拟机（如 Apple Silicon M1/M2）上运行 Jenkins：
- Cypress 的 Linux ARM64 安装包可能不存在
- 只有 macOS 的 ARM64 版本
解决方案：
| 方案 | 说明 |
|---|---|
| 移除 Cypress 依赖 | 项目中删除 Cypress（仅端到端测试需要） |
| 使用 x86 工作节点 | 在 x86 节点上执行包含 Cypress 的构建 |
| 排除端到端测试 | CI 流程中跳过 e2e 测试阶段 |
构建产物确认
构建成功后，Jenkins workspace 目录结构：
/workspace/frontend/
├── node_modules/
├── src/
├── public/
├── package.json
├── dist/ ← 构建产物（制品）
│ ├── index.html
│ ├── assets/
│ └── ...
└── ...
text
完整配置流程总结
1. 安装 NodeJS Plugin
↓
2. Global Tool Configuration → 添加 Node.js 版本
- 配置淘宝镜像源
- 安装全局包（cnpm, pnpm, yarn）
- 设置 registry 参数
↓
3. Managed Files → 创建 .npmrc 配置文件
↓
4. 系统配置 → 环境变量 → Cypress 下载镜像
↓
5. 任务配置 → Build Environment → 选择 Node.js 版本
↓
6. Build Steps → Execute shell → pnpm install && pnpm build
↓
7. 立即构建 → 验证控制台输出
text
↑